Multi-Agent Orchestration Plan V2 for Prompt and Agent File Creation

tech

github-copilot

prompt-engineering

agents

planning

Implementation plan for breaking down monolithic prompts into multi-agent orchestrations with use case validation and dependency planning

Author

Dario Airoldi

Published

December 26, 2025

Multi-Agent Orchestration Plan V2 for Prompt and Agent File Creation

Purpose: Comprehensive plan to break down monolithic *-createorupdate-*-v2.prompt.md files into robust, reliable multi-agent orchestrations with enhanced requirements validation.

Date: 2025-12-14
Version: 2.1
Status: Planning Phase
Updated: 2025-12-25 - Added v1.107 features (Agent HQ, “Continue in”, planning mode, work tree isolation)

Executive Summary

This plan refines the original multi-agent orchestration approach by:

Separating Design/Create from Review/Validate - Clear distinction between creation and validation workflows
Adding Use Case Challenge Validation - Goals and roles are actively tested against realistic scenarios
Integrating Agent Dependency Planning - Phases 5-6 handle agent updates and creation plans
Cross-Prompt Coordination - Agent creation plans flow to agent-design-and-create.prompt.md
Leveraging v1.107 Features - Agent HQ session management, “Continue in” delegation, planning mode, work tree isolation

v1.107 Enhancements

The orchestration system now leverages:

Agent HQ: Unified interface for tracking all orchestration phases across local/background/cloud sessions
“Continue in” Workflow: Primary delegation mechanism from orchestrator to specialist agents
Planning Mode: Optional Phase 0 for upfront implementation planning
Work Tree Isolation: Background agents run in isolated Git work trees to avoid conflicts
Session Management: Read/unread markers, filtering, archiving for complex multi-phase workflows

Files to Create/Update Summary

Category	Create	Update	Total
Orchestration Prompts	4	0	4
Agent Files	4	4	8
Instruction Files	0	0	0
Context Files	0	0	0

Total Files: 12 files (8 new, 4 updates)

Analysis of Source Prompts
Architecture Overview
Orchestration Prompts Specifications
Agent Specifications
Instruction Files Assessment
Handoff Flow Diagrams
📡 Communication Protocols & Information Contracts
📊 Data Exchange Optimization
Implementation Roadmap

Analysis of Source Prompts

Source 1: `prompt-createorupdate-prompt-file-v2.prompt.md`

Current Structure (1355 lines):

Phase 1: Input Analysis and Requirements Gathering
- Step 1: Determine Operation Type
- Step 2: Extract Initial Requirements
- Step 3: Determine Validation Depth (Adaptive)
- Step 4: Validate Requirements (Active Challenge-Based Discovery)
  - 4.1: Challenge Goal with Use Cases
  - 4.2: Validate Role Appropriateness
  - 4.3: Verify Workflow Reliability

Key Strengths to Preserve:

✅ Use case challenge validation (3/5/7 scenarios based on complexity)
✅ Three-tier boundary system (Always Do / Ask First / Never Do)
✅ Adaptive validation depth (Simple/Moderate/Complex)
✅ Role appropriateness testing (Authority/Expertise/Specificity tests)
✅ Tool composition validation

Issues to Address:

❌ Monolithic design (all phases in single prompt)
❌ No separation between design and validation
❌ Limited handoff orchestration
❌ Tool overload risk (needs 10+ tools for full workflow)

Source 2: `agent-createorupdate-agent-file-v2.prompt.md`

Current Structure (1394 lines):

Phase 1: Input Analysis and Requirements Gathering
- Step 1: Determine Operation Type
- Step 2: Extract Initial Requirements
- Step 3: Determine Validation Depth (Adaptive)
- Step 4: Validate Requirements
  - 4.1: Challenge Role with Use Cases
  - 4.2: Validate Tool Composition

Key Strengths to Preserve:

✅ Role challenge with realistic scenarios
✅ Tool composition validation (3-7 tools, agent/tool alignment)
✅ Handoff discovery (when agent needs to delegate)
✅ Scope boundary identification (IN/OUT of scope)
✅ Complexity assessment for validation depth

Issues to Address:

❌ Same monolithic issues as prompt version
❌ No coordination with dependent agent creation
❌ Missing clear phase separation for orchestration

Architecture Overview

Design Principles

Separation of Concerns
- Design/Create → Requirements + Research + Build
- Review/Validate → Validation + Issue Resolution
Narrow Tool Scope
- Each agent: 3-7 essential tools only
- Prevent tool clash through specialization
Clear Handoff Points
- User approval checkpoints at phase transitions
- Automatic handoffs within validation loops
- v1.107: “Continue in” buttons for delegating to background/cloud
Reusable Components
- Prompt agents reusable for prompt workflows
- Agent agents reusable for agent workflows
- Cross-pollination where appropriate
- v1.107: Same agents work across local/background/cloud contexts
Session Management (v1.107)
- Agent HQ tracks all orchestration phases
- Work tree isolation for background agents prevents conflicts
- Planning mode (optional Phase 0) for upfront design

Architecture Diagram

┌─────────────────────────────────────────────────────────────────────────┐
│                           USER REQUEST                                   │
│       "Create a prompt for X" / "Create an agent for Y"                 │
└───────────────────────────┬─────────────────────────────────────────────┘
                            │
            ┌───────────────┴───────────────┐
            │                               │
            ▼                               ▼
┌───────────────────────┐       ┌───────────────────────┐
│ PROMPT-DESIGN-AND-    │       │ AGENT-DESIGN-AND-     │
│ CREATE                │       │ CREATE                │
│ (Orchestrator)        │       │ (Orchestrator)        │
│ agent: plan (opt)     │       │ agent: plan (opt)     │
│ ▶ Agent HQ Session    │       │ ▶ Agent HQ Session    │
└───────────┬───────────┘       └───────────┬───────────┘
            │                               │
            │ Phase 0: Planning (if agent:plan)
            │ Phase 1-4                     │ Phase 1-6
            │ ▶ "Continue in" delegation    │ ▶ "Continue in" delegation
            │                               │
┌───────────┼───────────────────────────────┼───────────┐
│           │     RESEARCH & BUILD          │           │
│           │     (Background/Cloud)        │           │
│           ▼                               ▼           │
│   ┌──────────────┐               ┌──────────────┐     │
│   │   prompt-    │               │   agent-     │     │
│   │  researcher  │               │  researcher  │     │
│   │  ▶ Work Tree │               │  ▶ Work Tree │     │
│   └──────┬───────┘               └──────┬───────┘     │
│          │                              │             │
│          ▼                              ▼             │
│   ┌──────────────┐               ┌──────────────┐     │
│   │   prompt-    │               │   agent-     │     │
│   │   builder    │               │   builder    │     │
│   │  ▶ Work Tree │               │  ▶ Work Tree │     │
│   └──────────────┘               └──────────────┘     │
└───────────────────────────────────────────────────────┘
                            │
                            │ ▶ Agent HQ marks complete
                            ▼
┌───────────────────────────────────────────────────────┐
│                    VALIDATION                          │
│                  (Can run in Background)               │
│                                                        │
│   ┌──────────────┐               ┌──────────────┐     │
│   │   prompt-    │               │   agent-     │     │
│   │  validator   │               │  validator   │     │
│   └──────┬───────┘               └──────┬───────┘     │
│          │                              │             │
│          │ Issues?                      │ Issues?     │
│          ▼                              ▼             │
│   ┌──────────────┐               ┌──────────────┐     │
│   │   prompt-    │               │   agent-     │     │
│   │   updater    │               │   updater    │     │
│   └──────────────┘               └──────────────┘     │
└───────────────────────────────────────────────────────┘
                            │
                            ▼
            ┌───────────────┴───────────────┐
            │                               │
            ▼                               ▼
┌───────────────────────┐       ┌───────────────────────┐
│ PROMPT-REVIEW-AND-    │       │ AGENT-REVIEW-AND-     │
│ VALIDATE              │       │ VALIDATE              │
│ (For standalone       │       │ (For standalone       │
│  validation)          │       │  validation)          │
└───────────────────────┘       └───────────────────────┘

Legend:
  ▶ Agent HQ Session = Tracked in Agent HQ interface
  ▶ Work Tree = Runs in isolated Git work tree (background agents)
  ▶ "Continue in" = Delegation via "Continue in Background/Cloud" button

Orchestration Prompts Specifications

1. `prompt-design-and-create.prompt.md`

Status: ⬜ CREATE NEW (replace existing prompt-design-and-create.prompt.md)

Purpose: Orchestrate the complete design and creation workflow for new prompt files using specialized agents. Incorporates use case challenge validation from v2 monolithic prompts.

YAML Frontmatter

---
name: prompt-design-and-create
description: "Orchestrate prompt file design and creation using specialized agents with use case challenge validation"
agent: agent
model: claude-sonnet-4.5
tools:
  - semantic_search
  - read_file
handoffs:
  - label: "Research prompt requirements and patterns"
    agent: prompt-researcher
    send: false
  - label: "Build prompt file from validated specification"
    agent: prompt-builder
    send: false
  - label: "Validate prompt quality and compliance"
    agent: prompt-validator
    send: true
  - label: "Fix validation issues"
    agent: prompt-updater
    send: false
argument-hint: 'Describe the prompt purpose: what task it should accomplish, expected inputs/outputs, any constraints'
---

Role Definition

## Your Role

You are a **prompt creation workflow orchestrator** responsible for coordinating specialized agents to produce high-quality, validated prompt files.

**Your Expertise**:
- Requirements gathering and validation
- Use case challenge analysis
- Multi-agent workflow coordination
- Quality gate management

**You DO NOT**:
- Research patterns yourself (delegate to prompt-researcher)
- Create files yourself (delegate to prompt-builder)
- Validate files yourself (delegate to prompt-validator)
- Fix issues yourself (delegate to prompt-updater)

Phase Workflow

Phase 1: Requirements Gathering

Goal: Clarify what needs to be created, challenge with use cases, validate goal and role.

Orchestrator Activities:

Extract user intent from request
Determine prompt type (validation/implementation/orchestration)
Identify initial goal, role, and constraints

Handoff to @prompt-researcher:

context: |
  User Request: [user's description]
  Initial Analysis:
    - Prompt Type: [validation/implementation/orchestration]
    - Apparent Goal: [extracted goal]
    - Apparent Role: [inferred role]
  
  YOUR TASK - Challenge Requirements:
  1. Generate 3-7 use cases to test goal clarity (based on complexity)
  2. Identify ambiguities and gaps revealed by scenarios
  3. Test role appropriateness (authority/expertise/specificity)
  4. Identify CRITICAL BOUNDARIES (Always Do/Ask First/Never Do)
  5. If additional roles needed for phases, identify them
  
  Return: Validated requirements report with refined goal, role(s), boundaries

Decision Point: User reviews and approves requirements before Phase 2

Phase 1 Implementation Details: Use Case Challenge Protocol

This section provides the complete implementation for the Use Case Challenge methodology within Phase 1.

Step 1: Extract Initial Requirements

## Phase 1, Step 1: Initial Extraction

**Orchestrator Questions to User**:
1. What should this prompt/agent do? (primary purpose)
2. Single task or multi-phase workflow?
3. Read-only analysis or file modification?
4. Any specific patterns or examples to follow?

**Capture**:
- Apparent Goal: {user's stated purpose}
- Apparent Role: {inferred specialist type}
- Constraints: {any limitations mentioned}
- Initial Scope: {what's included/excluded}

Step 2: Determine Complexity Level

## Phase 1, Step 2: Complexity Assessment

**Assessment Criteria**:

| Level | Indicators | Use Cases to Generate |
|-------|----------|----------------------|
| **Simple** | • Single focused task<br>• Standard role (researcher, validator)<br>• Clear, bounded scope | 3 |
| **Moderate** | • 2-3 related objectives<br>• Domain-specific knowledge<br>• Some ambiguity in requirements | 5 |
| **Complex** | • Broad scope or multi-domain<br>• Novel workflow or patterns<br>• Unclear boundaries | 7 |

**Decision Output**:
Based on user's request, complexity level is: **{Simple/Moderate/Complex}**
Generate: **{3/5/7} use cases** for validation

Step 3: Use Case Challenge Execution

The orchestrator hands off to @prompt-researcher (or @agent-researcher) with this context:

context: |
  **Initial Requirements**:
  - Apparent Goal: {extracted goal}
  - Apparent Role: {inferred role}
  - Complexity: {Simple/Moderate/Complex}
  - Use Cases to Generate: {3/5/7}
  
  **YOUR TASK**: Challenge Goal with Use Cases
  
  For each use case:
  1. Create a realistic scenario where user would invoke this prompt/agent
  2. Test: Does the goal provide clear guidance for this case?
  3. Categorize result:
     - ✅ Clear: Goal handles this well
     - ⚠️ Ambiguous: Goal unclear for this case
     - ❌ Gap: Goal fails to address this scenario
  4. Document discoveries:
     - Tools Discovered: Tools needed for this scenario
     - Boundaries Discovered: Scope limits revealed
     - Refinement Needed: Specific goal adjustments
  
  **Output Format**: Use Case Challenge Results (template below)

Step 4: Expected Output Format

## Use Case Challenge Results

**Initial Goal**: "{user's original goal statement}"
**Complexity**: {Simple/Moderate/Complex}
**Use Cases Generated**: {3/5/7}

---

### Use Case 1: {Common Case Name} ✅ Clear
- **Scenario**: User has {typical situation}, wants {expected outcome}
- **Test**: Does goal cover this?
- **Result**: ✅ Goal clearly addresses this case
- **Tools Discovered**: {tools needed - e.g., read_file, grep_search}
- **Boundary Discovered**: IN SCOPE: {what's included}

### Use Case 2: {Edge Case Name} ⚠️ Ambiguous
- **Scenario**: User has {edge situation}, wants {unclear outcome}
- **Test**: Does goal cover this edge case?
- **Result**: ⚠️ Goal could mean X or Y (unclear)
- **Refinement Needed**: Clarify whether {aspect} is in scope
- **Tools Discovered**: {additional tools if different}

### Use Case 3: {Conflict Case Name} ❌ Gap
- **Scenario**: User wants {conflicting requirement}
- **Test**: Does goal address this conflict?
- **Result**: ❌ Goal doesn't provide guidance for this
- **Refinement Needed**: Explicitly include/exclude {aspect}
- **Boundary Discovered**: OUT OF SCOPE: {what should be excluded}

[Repeat for all {3/5/7} use cases]

---

## Validation Summary

| Result | Count | Use Cases |
|--------|-------|-----------|
| ✅ Clear | {N} | 1, 4, ... |
| ⚠️ Ambiguous | {N} | 2, 5, ... |
| ❌ Gap | {N} | 3, 6, ... |

## Refined Requirements

**Validation Status**: {✅ Clear / ⚠️ Needs Refinement / ❌ Critical Gaps}

**Refined Goal**: 
"{Updated goal incorporating all discoveries from use cases}"

**Scope Boundaries**:
- **IN SCOPE**: {comprehensive list of what's included}
- **OUT OF SCOPE**: {explicit exclusions discovered}

**Tool Requirements** (discovered from scenarios):
1. {tool-name} - {justification from which use case}
2. {tool-name} - {justification from which use case}
3. ...

**Critical Boundaries Discovered**:
- **Always Do**: {behaviors required in all cases}
- **Ask First**: {situations requiring user confirmation}
- **Never Do**: {prohibited actions discovered from edge cases}

**Agent Dependencies Identified**: {if complex workflow needs multiple agents}

Step 5: Orchestrator Presents to User

## Requirements Validation Complete

Based on use case challenge, the goal has been refined:

**Original Request**: "{user's original request}"

**Refined Goal**: 
"{Updated goal with specific scope and boundaries}"

**Scope Clarity**:
- ✅ **IN SCOPE**: {list}
- ❌ **OUT OF SCOPE**: {list}

**Tools Identified**: {list with count - must be 3-7}

**Boundaries Established**:
- Always: {list}
- Ask First: {list}
- Never: {list}

**Complexity Confirmed**: {Simple/Moderate/Complex}

---

**Proceed with this refined goal?** (yes/no/modify)

Step 6: Approval and Routing

## Decision Outcomes

**If "yes"**: 
→ Proceed to Phase 2 (Research) with validated requirements

**If "no" or "modify"**: 
→ User provides clarifications
→ Return to Step 1 with updated understanding
→ May need to re-run use case challenge if major changes

**If major architectural change revealed** (e.g., needs orchestrator + agents):
→ Update Architecture Decision in Phase 3 planning
→ Flag for agent dependency planning (Phases 5-6)

Integration: When Use Cases Reveal Agent Needs

If use case challenge reveals multi-domain complexity:

### Use Case 6: Complex Multi-Domain Validation ❌ Gap
- **Scenario**: User wants style + security + performance validation
- **Test**: Can single prompt handle all domains?
- **Result**: ❌ Too broad - requires 3 different expertise areas
- **Recommendation**: **Create orchestrator + 3 specialized agents**
  - `style-validator.agent.md`
  - `security-validator.agent.md`
  - `performance-validator.agent.md`
- **Architecture Decision**: Flag for Phase 3 (Architecture Analysis)

This discovery feeds into Phase 5-6: Agent Dependencies Planning.

Phase 2: Research and Pattern Discovery

Goal: Find proven patterns from .copilot/context/prompt-engineering/ and similar prompts.

Handoff to @prompt-researcher:

context: |
  Validated Requirements: [from Phase 1]
  
  YOUR TASK - Pattern Discovery (LOCAL ONLY):
  1. Search `.copilot/context/prompt-engineering/` for applicable patterns
     - context-engineering-principles.md
     - tool-composition-guide.md
     - validation-caching-pattern.md
  2. Find 3-5 similar existing prompts in `.github/prompts/`
  3. Extract common patterns, tool compositions
  4. Identify anti-patterns to avoid
  5. Select appropriate template from `.github/templates/`
  
  DO NOT: Search internet, fetch external URLs
  
  Return: Pattern analysis report with template recommendation

Decision Point: User reviews patterns and approves template selection

Phase 3: Prompt Structure Definition

Goal: Create complete specification before file creation.

Handoff to @prompt-researcher:

context: |
  Validated Requirements: [from Phase 1]
  Pattern Analysis: [from Phase 2]
  
  YOUR TASK - Define Complete Structure:
  1. Define YAML frontmatter (name, description, agent mode, tools, handoffs)
  2. Structure process phases with inputs/outputs
  3. Create tool justification list (3-7 tools only)
  4. Define three-tier boundaries
  5. Plan validation strategy
  6. Identify agent dependencies:
     - Existing agents this prompt will use
     - Existing agents that may need updates
     - New agents that may need to be created
  
  Return: Complete specification document

Decision Point: User approves specification before build

Phase 4: Prompt File Creation

Goal: Generate the prompt file following approved specification.

Handoff to @prompt-builder:

context: |
  Approved Specification: [from Phase 3]
  Template: [recommended template path]
  
  YOUR TASK - Create Prompt File:
  1. Load recommended template
  2. Apply all customizations from specification
  3. Implement three-tier boundaries
  4. Add examples (2-3 scenarios)
  5. Add bottom metadata block
  6. Save to .github/prompts/[name].prompt.md
  
  Return: Created file path, builder self-check results

Auto-Handoff: File automatically passed to validation

Phase 5: Create Plan for Agent Updates (Optional)

Goal: If Phase 3 identified existing agents needing updates, create plans.

Triggered When: Specification includes agents_to_update list

Orchestrator Activities:

Review agent update requirements from specification
Present update plan to user
Upon approval, create handoff package

Output:

## Agent Update Plan

### Agents Requiring Updates

**1. [agent-name].agent.md**
- **Current state**: [brief description]
- **Updates needed**: [specific changes]
- **Tools to add/remove**: [if any]
- **Boundaries to modify**: [if any]
- **Risk assessment**: [Low/Medium/High]

**2. [agent-name].agent.md**
[Same structure]

### Recommended Processing
Execute updates using: `@agent-review-and-validate` with update mode

**Approve update plan? (yes/no/modify)**

Decision Point: User approves before agent updates proceed

Phase 6: Create Plan for New Agents (Optional)

Goal: If Phase 3 identified new agents needed, create specifications.

Triggered When: Specification includes agents_to_create list

Orchestrator Activities:

Review new agent requirements from specification
Present creation plan to user
Upon approval, create handoff package

Output:

## New Agent Creation Plan

### Agents to Create

**1. [agent-name].agent.md**
- **Purpose**: [one-sentence description]
- **Role**: [specialist persona]
- **Tools**: [3-7 tools with justification]
- **Agent mode**: [plan/agent]
- **Boundaries**: [Always/Ask/Never]
- **Handoffs**: [if orchestrates other agents]
- **Template**: [recommended template]

**2. [agent-name].agent.md**
[Same structure]

### Recommended Processing
Create each agent using: `@agent-design-and-create`

**Approve creation plan? (yes/no/modify)**

Decision Point: User approves before agent creation proceeds

Phase 7: Quality Validation

Goal: Comprehensive validation against all standards.

Auto-Handoff to @prompt-validator:

context: |
  File Path: [created file path]
  Specification: [from Phase 3]
  
  YOUR TASK - Validate Prompt:
  1. Structure validation (YAML, sections, formatting)
  2. Convention compliance (naming, metadata)
  3. Pattern consistency (matches repository patterns)
  4. Quality assessment (clarity, completeness, boundaries)
  5. Tool/agent mode alignment check
  
  Return: Validation report with categorized findings

Decision Point:

✅ No critical issues: Complete - prompt ready for use
⚠️ Warnings only: User decides to fix or accept
❌ Critical issues: Proceed to Phase 8

Phase 8: Issue Resolution

Goal: Fix validation issues systematically.

Handoff to @prompt-updater:

context: |
  File Path: [prompt file path]
  Validation Report: [from Phase 7]
  
  YOUR TASK - Fix Issues:
  1. Parse validation report for specific issues
  2. Prioritize: Critical → Moderate → Minor
  3. Apply targeted fixes (include 3-5 lines context)
  4. Update metadata timestamps
  
  Return: Updated file, change summary

Loop: Return to Phase 7 for re-validation (max 3 iterations)

Boundaries

## 🚨 CRITICAL BOUNDARIES

### ✅ Always Do
- Gather complete requirements before any handoffs
- Challenge goals with use cases before accepting
- Wait for user approval at each phase transition
- Delegate all research/build/validate/update to specialists
- Validate files before declaring completion

### ⚠️ Ask First
- When requirements are ambiguous after use case challenge
- When Phase 3 identifies agent dependencies
- When validation finds critical issues (>3 iterations)

### 🚫 Never Do
- NEVER skip requirements gathering (Phase 1)
- NEVER skip use case challenge validation
- NEVER build without approved specification
- NEVER skip validation phase
- NEVER implement yourself - orchestrate only

2. `prompt-review-and-validate.prompt.md`

Status: 🔄 UPDATE EXISTING (enhance current implementation)

Purpose: Orchestrate validation of existing prompt files and coordinate targeted improvements.

YAML Frontmatter

---
name: prompt-review-and-validate
description: "Orchestrate prompt file validation, improvement, and issue resolution workflow"
agent: agent
model: claude-sonnet-4.5
tools:
  - read_file
  - semantic_search
  - grep_search
handoffs:
  - label: "Research improvement patterns and best practices"
    agent: prompt-researcher
    send: false
  - label: "Apply targeted improvements"
    agent: prompt-updater
    send: false
  - label: "Validate prompt quality"
    agent: prompt-validator
    send: true
argument-hint: 'Provide path to existing prompt file, or attach with #file, optionally describe specific concerns'
---

Phase Workflow

Phase 1: File Analysis

Load and parse target prompt file
Identify structure, type, current state
Detect potential issues (structure, tools, boundaries)

Phase 2: Pattern Research (Optional)

If improvements needed, research current best practices
Find patterns in high-quality similar prompts

Phase 3: Validation

Comprehensive validation via @prompt-validator
Generate categorized report

Phase 4: Improvement Planning

Analyze validation findings
Create targeted improvement plan
Preserve core behavior

Phase 5: Issue Resolution

Apply fixes via @prompt-updater
Re-validate until no critical issues

3. `agent-design-and-create.prompt.md`

Status: ⬜ CREATE NEW

Purpose: Orchestrate the complete design and creation workflow for new agent files. Handles agent dependency chains and role challenge validation.

YAML Frontmatter

---
name: agent-design-and-create
description: "Orchestrate agent file design and creation with role challenge validation and dependency handling"
agent: agent
model: claude-sonnet-4.5
tools:
  - semantic_search
  - read_file
handoffs:
  - label: "Research agent requirements and patterns"
    agent: agent-researcher
    send: false
  - label: "Build agent file from validated specification"
    agent: agent-builder
    send: false
  - label: "Validate agent quality and compliance"
    agent: agent-validator
    send: true
  - label: "Fix validation issues"
    agent: agent-updater
    send: false
argument-hint: 'Describe the agent role and purpose: what specialist persona, what tasks it handles, any tool requirements'
---

Phase Workflow

Phase 1: Requirements Gathering

Goal: Clarify agent role, challenge with use cases, validate tool requirements.

Handoff to @agent-researcher:

context: |
  User Request: [user's description]
  Initial Analysis:
    - Apparent Role: [inferred specialist role]
    - Apparent Mode: [plan for read-only, agent for write access]
    - Apparent Tools: [inferred from role type]
  
  YOUR TASK - Challenge Requirements:
  1. Generate 3-7 use cases to test role specialization
  2. Identify: Is role too broad? Too narrow?
  3. Discover tool requirements from scenarios
  4. Test agent/tool alignment (plan → read-only, agent → full access)
  5. Identify handoff needs (does agent need to delegate?)
  6. Define scope boundaries (IN SCOPE vs OUT OF SCOPE)
  7. Establish CRITICAL BOUNDARIES (Always Do/Ask First/Never Do)
  
  Return: Validated requirements with refined role, tools (3-7), boundaries

Role Challenge Output Format:

### Role Challenge Results

**Initial Role**: [starting role definition]
**Use Cases Generated**: [3/5/7]

**Use Case 1**: [scenario]
- Test: [question about role capability]
- Result: [✅ Clear / ⚠️ Ambiguous / ❌ Gap]
- Tool Discovered: [if scenario reveals tool need]
- Boundary Discovered: [if scenario reveals scope limit]
- Refinement: [specific role adjustment]

[Repeat for all use cases]

**Validation Status**:
- ✅ Role appropriately specialized → Proceed
- ⚠️ Role needs refinement → [proposed changes, ask user]
- ❌ Role fundamentally flawed → BLOCK, ask user for direction

**Refined Role**: [updated role definition]
**Tools Discovered**: [list with justifications]
**Handoffs Needed**: [if agent should delegate to others]
**Scope Boundaries**: IN: [list] / OUT: [list]

Decision Point: User approves requirements

Phase 2: Research and Pattern Discovery

Goal: Find patterns from context files and similar agents.

Handoff to @agent-researcher:

context: |
  Validated Requirements: [from Phase 1]
  
  YOUR TASK - Pattern Discovery (LOCAL ONLY):
  1. Search `.copilot/context/prompt-engineering/` for applicable patterns
     - context-engineering-principles.md
     - tool-composition-guide.md (CRITICAL for agent tool selection)
  2. Find 3-5 similar existing agents in `.github/agents/`
  3. Extract tool composition patterns
  4. Identify successful role definitions
  5. Note anti-patterns (tool overload, broad scope)
  
  Return: Pattern analysis with tool composition recommendations

Phase 3: Agent Structure Definition

Goal: Create complete specification before file creation.

Handoff to @agent-researcher:

context: |
  Validated Requirements: [from Phase 1]
  Pattern Analysis: [from Phase 2]
  
  YOUR TASK - Define Complete Structure:
  1. Define YAML frontmatter:
     - description (one-sentence)
     - agent mode (plan/agent)
     - tools (3-7 MAXIMUM with justification)
     - handoffs (if agent coordinates others)
  2. Define role/persona with expertise areas
  3. Structure responsibilities (primary tasks)
  4. Create three-tier boundaries
  5. Plan validation strategy
  6. Identify dependencies:
     - Existing agents this agent will hand off to
     - Existing agents that may need updates
     - New supporting agents needed
  
  CRITICAL: Tools MUST be 3-7 only. If >7 needed, decompose into multiple agents.
  
  Return: Complete specification document

Decision Point: User approves specification

Phase 4: Agent File Creation

Goal: Generate the agent file.

Handoff to @agent-builder:

context: |
  Approved Specification: [from Phase 3]
  
  YOUR TASK - Create Agent File:
  1. Apply specification to agent file structure
  2. Implement persona/role definition
  3. Configure tools (MUST be 3-7)
  4. Implement three-tier boundaries
  5. Add bottom metadata block
  6. Save to .github/agents/[name].agent.md
  
  Return: Created file path, tool count verification

Phase 5: Plan for Agent Updates

Goal: If dependencies identified, create update plans.

Same structure as prompt-design-and-create Phase 5

Phase 6: Plan for New Agent Creation

Goal: If new supporting agents needed, create specifications.

Orchestrator Activities:

Review new agent specifications from Phase 3
Present creation plan to user
Upon approval, create handoff to self (recursive)

Recursive Handling:

## New Agent Creation Queue

**Maximum recursion depth**: 2 levels (prevent infinite loops)

**Agents to Create**:
1. [agent-name] - [will be created via @agent-design-and-create]
2. [agent-name] - [will be created via @agent-design-and-create]

**Processing Order**:
1. Complete current agent creation
2. Run validation
3. If passed, process agent creation queue
4. Each queued agent triggers new @agent-design-and-create workflow

**Approve and proceed? (yes/no/modify)**

Phase 7: Quality Validation

Auto-Handoff to @agent-validator:

context: |
  File Path: [created file path]
  Specification: [from Phase 3]
  
  YOUR TASK - Validate Agent:
  1. Structure validation (YAML, sections)
  2. Tool count validation (MUST be 3-7)
  3. Agent/tool alignment (plan → read-only, agent → write-capable)
  4. Boundary completeness (three-tier)
  5. Convention compliance
  6. Handoff validity (target agents exist)
  
  Return: Validation report with categorized findings

Phase 8: Issue Resolution

Same structure as prompt-design-and-create Phase 8, using @agent-updater

4. `agent-review-and-validate.prompt.md`

Status: ⬜ CREATE NEW

Purpose: Orchestrate validation of existing agent files with focus on tool alignment and role clarity.

YAML Frontmatter

---
name: agent-review-and-validate
description: "Orchestrate agent file validation with tool alignment checks and issue resolution"
agent: agent
model: claude-sonnet-4.5
tools:
  - read_file
  - semantic_search
  - grep_search
handoffs:
  - label: "Research improvement patterns"
    agent: agent-researcher
    send: false
  - label: "Apply targeted improvements"
    agent: agent-updater
    send: false
  - label: "Validate agent quality"
    agent: agent-validator
    send: true
argument-hint: 'Provide path to existing agent file, or attach with #file'
---

Phase Workflow

Phase 1: File Analysis

Load target agent file
Parse: role, tools, mode, boundaries
Check tool count (flag if >7)
Check agent/tool alignment

Phase 2: Validation

Comprehensive validation via @agent-validator
Special focus on:
- Tool count compliance
- Agent mode / tool alignment
- Boundary completeness

Phase 3: Improvement Planning

Analyze validation findings
Create targeted improvement plan
If tool count >7, recommend decomposition

Phase 4: Issue Resolution

Apply fixes via @agent-updater
Re-validate until compliant

Agent Specifications

Existing Agents to UPDATE (4 files)

1. `prompt-researcher.agent.md`

Status: 🔄 UPDATE - Add use case challenge capabilities

Current File: .github/agents/prompt-researcher.agent.md (604 lines)

Updates Needed:

Section	Current	Add/Modify
Role	Research specialist	Add “Requirements analyst” capability
Phase 1	Requirements Clarification	Add use case challenge generation
New Section	N/A	Add “Use Case Challenge Methodology”
Output Templates	Basic requirements summary	Add challenge results template

New Process Step to Add:

### Phase 1a: Use Case Challenge Validation (NEW)

**Goal**: Test goal clarity through realistic scenarios.

**Process**:
1. Determine complexity level (Simple/Moderate/Complex)
2. Generate use cases (3/5/7 based on complexity)
3. Test each scenario against goal:
   - Does goal provide clear guidance?
   - What gaps or ambiguities revealed?
   - What tools/boundaries discovered?
4. Refine goal based on findings

**Use Case Generation Guidelines**:

| Complexity | Indicators | Use Cases |
|------------|------------|-----------|
| Simple | Clear single task, standard role | 3 |
| Moderate | Multiple objectives, domain-specific | 5 |
| Complex | Broad scope, novel workflow | 7 |

**Output: Challenge Results**
```markdown
### Use Case Challenge Results

**Complexity Assessment**: [Simple/Moderate/Complex]
**Use Cases Generated**: [N]

**Use Case 1: [Common Case]**
- Scenario: [realistic situation]
- Test: [question about goal applicability]
- Current Guidance: [what goal says to do]
- Gap Identified: [ambiguity or missing info]
- Refinement: [specific change to goal]

[Repeat for all use cases]

**Validation Status**: [✅ Clear / ⚠️ Needs Refinement / ❌ Critical Gaps]
**Refined Goal**: [updated goal incorporating discoveries]


---

#### 2. `prompt-builder.agent.md`

**Status**: 🔄 UPDATE - Minor enhancements

**Current File**: `.github/agents/prompt-builder.agent.md` (620 lines)

**Updates Needed**:

| Section | Current | Add/Modify |
|---------|---------|------------|
| **Tool validation** | Basic structure check | Add tool count verification (3-7) |
| **Boundaries section** | Template-based | Ensure three-tier enforcement |
| **Metadata** | Basic | Add creation context tracking |

**New Validation Step to Add**:

```markdown
### Phase 3a: Pre-Save Validation (NEW)

**Before saving file, verify**:
- [ ] Tool count: [count] (MUST be 3-7)
- [ ] Agent mode matches tool types
- [ ] Three-tier boundaries complete
- [ ] Bottom metadata block present
- [ ] Examples included (minimum 2)

**If any check fails**: STOP, report issue, do not save

3. `prompt-updater.agent.md`

Status: 🔄 UPDATE - Add change categorization

Current File: .github/agents/prompt-updater.agent.md (699 lines)

Updates Needed:

Section	Current	Add/Modify
Change planning	List-based	Add impact categorization
Risk assessment	Implicit	Make explicit per-change

New Change Categorization to Add:

### Change Impact Categories (NEW)

**Classify each change before applying**:

| Category | Description | Approval Needed |
|----------|-------------|-----------------|
| **Structural** | Adds/removes sections, changes phase flow | Yes |
| **Behavioral** | Modifies boundaries, tool access | Yes |
| **Cosmetic** | Formatting, wording improvements | No |
| **Fix** | Corrects errors identified in validation | No |

**Update Plan Template**:
```markdown
### Change 1: [Description]
- **Type**: [Structural/Behavioral/Cosmetic/Fix]
- **Impact**: [High/Medium/Low]
- **Approval**: [Required/Auto-apply]
- **Lines**: [N-M]
- **Before**: [excerpt]
- **After**: [excerpt]


---

#### 4. `prompt-validator.agent.md`

**Status**: 🔄 UPDATE - Add tool alignment checks

**Current File**: `.github/agents/prompt-validator.agent.md` (648 lines)

**Updates Needed**:

| Section | Current | Add/Modify |
|---------|---------|------------|
| **Tool validation** | Basic presence check | Add count and alignment validation |
| **Scoring** | Structure-focused | Add tool composition score |

**New Validation Checks to Add**:

```markdown
### Phase 3a: Tool Composition Validation (NEW)

**Checks**:
1. **Tool Count**: [count] 
   - ✅ 3-7 tools: Optimal
   - ⚠️ <3 tools: May be insufficient
   - ❌ >7 tools: Tool clash risk - FAIL

2. **Agent/Tool Alignment**:
   - `agent: plan` + write tools → ❌ FAIL
   - `agent: agent` + only read tools → ⚠️ Warning (may be intentional)
   
3. **Tool Redundancy**:
   - Check for overlapping capabilities
   - Recommend consolidation if found

**Output: Tool Composition Score**
```markdown
### Tool Composition
- **Count**: [N] [✅/⚠️/❌]
- **Alignment**: [agent mode] + [tool types] [✅/❌]
- **Redundancy**: [None/Minor/Significant]
- **Score**: [X]/100


---

### New Agents to CREATE (4 files)

---

#### 5. `agent-researcher.agent.md`

**Status**: ⬜ CREATE NEW

**Purpose**: Research specialist for agent file requirements and pattern discovery. Parallel to `prompt-researcher` but specialized for agent concerns.

#### Full Specification

```yaml
---
name: agent-researcher
description: "Research specialist for agent file requirements and pattern discovery with role challenge validation"
agent: plan
model: claude-sonnet-4.5
tools:
  - semantic_search    # Find similar agents and patterns
  - grep_search        # Search for specific patterns
  - read_file          # Read templates and context files
  - file_search        # Locate agent files
  - list_dir           # Explore agent directory
handoffs:
  - label: "Build Agent"
    agent: agent-builder
    send: false
---

Role Definition

# Agent Researcher

You are a **research specialist** focused on analyzing agent requirements and discovering implementation patterns. You excel at challenging role definitions with use cases, identifying tool requirements, and validating agent/tool alignment. You NEVER create or modify files—you only research and report.

## Your Expertise

- **Role Challenge Analysis**: Testing agent roles against realistic scenarios
- **Tool Discovery**: Identifying minimum essential tools from use cases
- **Pattern Recognition**: Finding similar agents and extracting patterns
- **Alignment Validation**: Ensuring agent mode matches tool requirements
- **Scope Definition**: Identifying IN SCOPE vs OUT OF SCOPE boundaries

Key Processes

## Process

### Phase 1: Requirements Clarification with Role Challenge

1. **Understand Primary Role**
   - What specialist persona is needed?
   - What tasks will this agent handle?
   - What mode: read-only analysis (plan) or active modification (agent)?

2. **Challenge Role with Use Cases**
   - Generate 3-7 scenarios based on complexity
   - Test each: Can this role handle effectively?
   - Identify gaps, overlaps, ambiguities
   - Discover tool requirements from scenarios
   - Find handoff needs (when to delegate)

3. **Validate Tool Requirements**
   - Map responsibilities → capabilities → tools
   - Enforce 3-7 tool limit (decompose if >7)
   - Verify agent/tool alignment:
     - `agent: plan` → ONLY read-only tools
     - `agent: agent` → read + write tools allowed

**Output: Validated Requirements**
```markdown
### Agent Requirements Summary

**Role**: [refined specialist role]
**Mode**: [plan/agent]
**Complexity**: [Simple/Moderate/Complex]

**Use Case Challenge Results**:
- [Use case 1]: [result]
- [Use case 2]: [result]
- [N more...]

**Tool Requirements** (3-7 only):
1. [tool-name] - [justification from use case]
2. [tool-name] - [justification from use case]
...

**Scope Boundaries**:
- IN SCOPE: [what agent handles]
- OUT OF SCOPE: [what's excluded or delegated]

**Handoffs Needed**: [other agents to coordinate with]

**Validation Status**: [✅/⚠️/❌]

Phase 2: Pattern Discovery

[Same structure as prompt-researcher Phase 2, but searching .github/agents/]

Phase 3: Structure Definition

[Same structure as prompt-researcher Phase 3, but with agent-specific fields]


#### Boundaries

```markdown
## 🚨 CRITICAL BOUNDARIES

### ✅ Always Do
- Challenge EVERY role with at least 3 use cases
- Verify tool count is 3-7 (NEVER approve >7)
- Check agent/tool alignment (plan → read-only only)
- Cross-reference tool-composition-guide.md
- Provide specific justification for each tool
- Identify scope boundaries clearly

### ⚠️ Ask First
- When role seems too broad (suggest decomposition)
- When >7 tools seem needed (MUST decompose)
- When agent/tool alignment is ambiguous

### 🚫 Never Do
- NEVER create or modify files
- NEVER skip role challenge phase
- NEVER approve >7 tools
- NEVER mix `agent: plan` with write tools
- NEVER proceed to building without validated requirements

6. `agent-builder.agent.md`

Status: ⬜ CREATE NEW

Purpose: File creation specialist for agent files. Parallel to prompt-builder.

Full Specification

---
name: agent-builder
description: "Agent file generator following validated patterns and templates"
agent: agent
model: claude-sonnet-4.5
tools:
  - read_file          # Load templates and context
  - semantic_search    # Find similar patterns
  - create_file        # Create new agent file
  - file_search        # Locate reference files
handoffs:
  - label: "Validate Agent"
    agent: agent-validator
    send: true
---

Role Definition

# Agent Builder

You are an **agent generation specialist** focused on creating high-quality agent files from validated specifications. You excel at implementing role definitions, configuring tools, and establishing clear boundaries. You create new files but do NOT modify existing agents.

## Your Expertise

- **Role Implementation**: Translating role specifications into agent personas
- **Tool Configuration**: Setting up 3-7 essential tools with proper alignment
- **Boundary Definition**: Creating comprehensive three-tier boundaries
- **Pattern Application**: Following repository conventions and templates

Boundaries

## 🚨 CRITICAL BOUNDARIES

### ✅ Always Do
- Verify specification has validated requirements
- Check tool count is 3-7 before creating
- Verify agent/tool alignment before saving
- Include complete three-tier boundaries
- Add bottom metadata block
- Hand off to validator automatically

### ⚠️ Ask First
- When specification seems incomplete
- When tool count is at boundary (3 or 7)
- When handoff targets don't exist yet

### 🚫 Never Do
- NEVER modify existing agents (updater's role)
- NEVER create agent with >7 tools
- NEVER mix plan mode with write tools
- NEVER skip validation handoff

7. `agent-updater.agent.md`

Status: ⬜ CREATE NEW

Purpose: Update specialist for existing agent files. Parallel to prompt-updater.

Full Specification

---
name: agent-updater
description: "Specialized updater for existing agent files with tool alignment preservation"
agent: agent
model: claude-sonnet-4.5
tools:
  - read_file                    # Read current state
  - grep_search                  # Find patterns to update
  - replace_string_in_file       # Single updates
  - multi_replace_string_in_file # Batch updates
handoffs:
  - label: "Re-validate After Update"
    agent: agent-validator
    send: true
---

Key Processes

## Process

### Phase 1: Update Planning

1. **Analyze Update Request**
   - Validation report with issues?
   - User-specified changes?
   - Tool realignment needed?

2. **Read Current Agent**
   - Load complete file
   - Parse YAML (tools, mode, handoffs)
   - Verify line numbers from validation report

3. **Plan Updates with Impact Assessment**
   - Categorize each change (Structural/Behavioral/Cosmetic/Fix)
   - Check: Will update break agent/tool alignment?
   - Check: Will update exceed 7-tool limit?
   - If either: STOP, report issue, ask for guidance

### Phase 2: Apply Updates

[Same as prompt-updater but with agent-specific validations]

### Phase 3: Post-Update Verification

**Before handoff to validator, verify**:
- [ ] Tool count still 3-7
- [ ] Agent/tool alignment preserved
- [ ] Boundaries still three-tier complete
- [ ] Handoff targets still valid

Boundaries

## 🚨 CRITICAL BOUNDARIES

### ✅ Always Do
- Read complete file before any changes
- Verify agent/tool alignment after changes
- Verify tool count remains 3-7
- Include 3-5 lines context in replacements
- Hand off to validator for re-validation

### ⚠️ Ask First
- Before changes that affect tool count
- Before changes that affect agent mode
- Before removing or adding handoffs

### 🚫 Never Do
- NEVER create new files
- NEVER update without reading first
- NEVER break agent/tool alignment
- NEVER exceed 7-tool limit
- NEVER skip re-validation

8. `agent-validator.agent.md`

Status: ⬜ CREATE NEW

Purpose: Quality assurance specialist for agent files. Parallel to prompt-validator with agent-specific checks.

Full Specification

---
name: agent-validator
description: "Quality assurance specialist for agent file validation with tool alignment verification"
agent: plan
model: claude-sonnet-4.5
tools:
  - read_file      # Load files to validate
  - grep_search    # Search for patterns
  - file_search    # Find reference files
---

Key Validation Checks

## Validation Checks

### Agent-Specific Checks (Priority)

1. **Tool Count Validation** (CRITICAL)
   - Count tools in YAML array
   - ❌ FAIL if >7 tools
   - ⚠️ WARN if <3 tools
   - ✅ PASS if 3-7 tools

2. **Agent/Tool Alignment** (CRITICAL)
   - Parse `agent:` field
   - Parse `tools:` array
   - Check alignment:
     - `agent: plan` + ANY write tool → ❌ FAIL
     - `agent: agent` + only read tools → ⚠️ WARN
     - Proper alignment → ✅ PASS
   - Write tools: create_file, replace_string_in_file, multi_replace_string_in_file, run_in_terminal

3. **Handoff Validity**
   - Parse `handoffs:` array
   - For each handoff target:
     - Check if target agent file exists
     - Verify target is valid agent name
   - ❌ FAIL if any target doesn't exist

4. **Role/Persona Validation**
   - Check for clear role definition section
   - Verify expertise areas defined
   - Check for specialist focus (not generic)

### Standard Checks (Same as prompt-validator)
- Structure validation
- Convention compliance  
- Pattern consistency
- Quality assessment

Output Format

### Validation Report: [agent-name]

**Overall Status**: [✅ PASSED / ⚠️ WARNINGS / ❌ FAILED]

**Agent-Specific Checks**:
| Check | Result | Details |
|-------|--------|---------|
| Tool Count | [✅/⚠️/❌] | [N] tools (3-7 required) |
| Agent/Tool Alignment | [✅/⚠️/❌] | [mode] + [tool types] |
| Handoff Validity | [✅/⚠️/❌] | [N] handoffs, [M] valid |
| Role Definition | [✅/⚠️/❌] | [assessment] |

**Standard Checks**:
| Check | Score | Details |
|-------|-------|---------|
| Structure | [X]/100 | [findings] |
| Conventions | [X]/100 | [findings] |
| Patterns | [X]/100 | [findings] |
| Quality | [X]/100 | [findings] |

**Issues by Severity**:
- **Critical** ([N]): [list with line numbers]
- **Moderate** ([N]): [list with line numbers]
- **Minor** ([N]): [list with line numbers]

**Recommendations**:
1. [Specific fix with line reference]
2. [Specific fix with line reference]

Instruction Files Assessment

`.github/instructions/prompts.instructions.md`

Status: ✅ NO CHANGES NEEDED

Assessment: Current file is comprehensive and covers:

Context engineering principles reference
Tool selection guidance
Repository-specific patterns
Naming conventions
Template references

`.github/instructions/agents.instructions.md`

Status: ✅ NO CHANGES NEEDED

Assessment: Current file is comprehensive and covers:

Context engineering principles reference
Tool selection (3-7 tool rule documented)
Agent/tool alignment guidance
Six essential agent patterns
Multi-agent orchestration guidance

Handoff Flow Diagrams

Prompt Design and Create Flow

User Request
    │
    ▼
┌────────────────────────────────────────────────────────────┐
│                 PHASE 1: Requirements                       │
│                                                             │
│  Orchestrator ──► prompt-researcher (challenge with cases) │
│       │                    │                                │
│       │◄───────────────────┘ Requirements Report            │
│       │                                                     │
│       ▼                                                     │
│  [User Approval Checkpoint]                                 │
└────────────────────────────────────────────────────────────┘
    │
    ▼
┌────────────────────────────────────────────────────────────┐
│                 PHASE 2: Research                           │
│                                                             │
│  Orchestrator ──► prompt-researcher (pattern discovery)    │
│       │                    │                                │
│       │◄───────────────────┘ Pattern Report                 │
│       │                                                     │
│       ▼                                                     │
│  [User Approval Checkpoint]                                 │
└────────────────────────────────────────────────────────────┘
    │
    ▼
┌────────────────────────────────────────────────────────────┐
│                 PHASE 3: Structure                          │
│                                                             │
│  Orchestrator ──► prompt-researcher (define structure)     │
│       │                    │                                │
│       │◄───────────────────┘ Specification                  │
│       │                                                     │
│       ▼                                                     │
│  [User Approval Checkpoint]                                 │
└────────────────────────────────────────────────────────────┘
    │
    ▼
┌────────────────────────────────────────────────────────────┐
│                 PHASE 4: Build                              │
│                                                             │
│  Orchestrator ──► prompt-builder (create file)             │
│       │                    │                                │
│       │◄───────────────────┘ File Created                   │
└────────────────────────────────────────────────────────────┘
    │
    ▼
┌────────────────────────────────────────────────────────────┐
│            PHASE 5-6: Agent Plans (if needed)               │
│                                                             │
│  If agents to update: Create plan ──► agent-review-validate │
│  If agents to create: Create plan ──► agent-design-create   │
│                                                             │
│  [User Approval Checkpoint for each plan]                   │
└────────────────────────────────────────────────────────────┘
    │
    ▼
┌────────────────────────────────────────────────────────────┐
│                 PHASE 7: Validation                         │
│                                                             │
│  Orchestrator ──► prompt-validator (AUTO handoff)          │
│       │                    │                                │
│       │◄───────────────────┘ Validation Report              │
│       │                                                     │
│       ▼                                                     │
│  [Decision: Pass/Warn/Fail]                                 │
└────────────────────────────────────────────────────────────┘
    │
    ├──────────────────────┐
    │ If PASS             │ If FAIL
    ▼                      ▼
┌──────────────┐    ┌────────────────────────────────────────┐
│   COMPLETE   │    │         PHASE 8: Fix Issues            │
│   ✅          │    │                                        │
└──────────────┘    │  Orchestrator ──► prompt-updater       │
                    │       │                    │            │
                    │       │◄───────────────────┘ Updated    │
                    │       │                                 │
                    │       ▼                                 │
                    │  [Loop back to Phase 7, max 3x]         │
                    └────────────────────────────────────────┘

Agent Design and Create Flow

User Request
    │
    ▼
┌────────────────────────────────────────────────────────────┐
│                 PHASE 1: Requirements                       │
│                                                             │
│  Orchestrator ──► agent-researcher (role challenge)        │
│       │                    │                                │
│       │◄───────────────────┘ Requirements (tools 3-7)       │
│       │                                                     │
│       ▼                                                     │
│  [User Approval + Tool Count Verification]                  │
└────────────────────────────────────────────────────────────┘
    │
    ▼
┌────────────────────────────────────────────────────────────┐
│                 PHASE 2-3: Research + Structure             │
│                                                             │
│  [Same as Prompt flow but with agent-specific checks]       │
└────────────────────────────────────────────────────────────┘
    │
    ▼
┌────────────────────────────────────────────────────────────┐
│                 PHASE 4: Build                              │
│                                                             │
│  Orchestrator ──► agent-builder (create file)              │
│       │                    │                                │
│       │◄───────────────────┘ File + Tool Count Verification │
│       │                                                     │
│       │  ⚠️ GATE: If tools >7, REJECT and go back          │
└────────────────────────────────────────────────────────────┘
    │
    ▼
┌────────────────────────────────────────────────────────────┐
│            PHASE 5-6: Agent Dependencies                    │
│                                                             │
│  If agents to update ──► agent-review-and-validate         │
│  If agents to create ──► RECURSIVE agent-design-and-create │
│                                                             │
│  ⚠️ Max recursion depth: 2 levels                          │
│                                                             │
│  [User Approval Required for each]                          │
└────────────────────────────────────────────────────────────┘
    │
    ▼
┌────────────────────────────────────────────────────────────┐
│                 PHASE 7: Validation                         │
│                                                             │
│  Orchestrator ──► agent-validator (AUTO)                   │
│       │                    │                                │
│       │◄───────────────────┘ Report + Tool Alignment Check  │
│       │                                                     │
│       │  ⚠️ CRITICAL: Fail if tools >7 or alignment wrong  │
│       ▼                                                     │
│  [Decision: Pass/Warn/Fail]                                 │
└────────────────────────────────────────────────────────────┘
    │
    ├──────────────────────┐
    │ If PASS             │ If FAIL
    ▼                      ▼
┌──────────────┐    ┌────────────────────────────────────────┐
│   COMPLETE   │    │         PHASE 8: Fix Issues            │
│   ✅          │    │                                        │
└──────────────┘    │  Orchestrator ──► agent-updater        │
                    │       │                                 │
                    │       │  ⚠️ Preserve tool alignment     │
                    │       │  ⚠️ Maintain 3-7 tool count     │
                    │       │                                 │
                    │       ▼                                 │
                    │  [Loop back to Phase 7, max 3x]         │
                    └────────────────────────────────────────┘

Communication Protocols & Information Contracts

Phase-to-Phase Data Flow

Each phase in the workflow has explicit input/output contracts to ensure reliability and token efficiency:

Phase	Input Contract	Output Contract	Token Budget
Phase 1: Requirements	User request (text)	Validated requirements document	500-1,000
Phase 2: Research	Requirements + search queries	Research report (patterns, templates)	2,000-4,000
Phase 3: Structure	Research summary (compressed)	Complete specification (YAML + structure)	1,000-2,000
Phase 4: Build	Specification + template reference	File path + self-check results	1,500-3,000
Phase 5: Validation	File path + specification	Validation report (pass/fail + issues)	1,000-2,000
Phase 6: Update	Validation report + file path	Updated file path + change summary	1,000-2,000

Information Compression Between Phases

Key Principle: Each phase produces a compressed summary for downstream consumption, not full context.

## Phase 2 → Phase 3 Handoff (Research → Structure)

### Phase 2 Full Output (3,000 tokens):
```markdown
# Research Report: Validation Prompts

## Context Summary
Analyzed 5 existing validation prompts...
[Full analysis with examples, anti-patterns, discovery process]

Compressed Handoff to Phase 3 (500 tokens):

## Research Findings Summary

**Key Patterns to Apply**:
1. Structured output format (reference: prompt-1.md)
2. Three-tier boundaries (reference: prompt-2.md)
3. Severity categorization (reference: prompt-3.md)

**Template Recommendation**: validation-template.md
**Critical Constraints**: Tool count 3-7, read-only mode
**Anti-patterns to Avoid**: Unbounded loops, missing checkpoints


### Handoff Prompt Template (Token-Optimized)

Use this structure for all phase transitions:

```yaml
handoffs:
  - label: "{Action Description}"
    agent: {target-agent}
    send: true
    prompt: |
      {Primary Task Statement - 1 sentence}
      
      **Context from Previous Phase** (reference, not embed):
      - See above for: {what's in conversation history}
      - Specification: {reference Phase 3 output}
      
      **Your Specific Inputs**:
      - {Input 1}: {value or reference}
      - {Input 2}: {value or reference}
      
      **Expected Output Format**:
      {Structured template for this agent's response}
      
      **Success Criteria**:
      - {Criterion 1}
      - {Criterion 2}

Example: Phase 4 → Phase 5 Handoff (Build → Validation)

handoffs:
  - label: "Validate Prompt Quality"
    agent: prompt-validator
    send: true
    prompt: |
      Validate the prompt file created above.
      
      **Context from Previous Phases**:
      - Specification: See Phase 3 output in conversation
      - Template used: {template-path from build phase}
      
      **Your Validation Inputs**:
      - File path: {created-file-path}
      - Expected tool count: 3-7
      - Expected mode: {agent-mode from spec}
      
      **Expected Output Format**:
      Validation report with:
      - Overall status (PASS/FAIL/WARN)
      - Check results table
      - Categorized issues (Critical/Moderate/Minor)
      - Recommended fixes for updater
      
      **Success Criteria**:
      - All structural checks pass
      - Tool count within bounds
      - Agent/tool alignment validated

Selective Context Passing Rules

For each phase transition, follow these rules:

Handoff	INCLUDE	EXCLUDE
Orch → Researcher	User request, initial goal, constraints	N/A (first phase)
Researcher → Orchestrator	Pattern summary, template recommendation	Discovery process, all search results
Orch → Builder	Specification, template path, boundaries	Research details, use case challenge history
Builder → Validator	File path, spec reference, expected mode	Build process, template loading steps
Validator → Updater	Issue list with line numbers, fix recommendations	Passing checks, validation methodology

Reliability Checksum Pattern

Before each handoff, orchestrator validates critical data survives:

## Phase Transition Checklist (Orchestrator Internal)

Before Phase {N} → Phase {N+1}:

- [ ] **Goal Preservation**: Refined goal from Phase 1 intact?
- [ ] **Scope Boundaries**: IN/OUT scope carried forward?
- [ ] **Tool Requirements**: Tool list present in handoff?
- [ ] **Critical Constraints**: Boundaries included?
- [ ] **Success Criteria**: Validation criteria defined?

**If ANY fails**: Re-inject missing context before handoff.

📊 Data Exchange Optimization

This section defines token-efficient data exchange strategies for agent handoffs, ensuring maximum reliability while minimizing context overhead.

Token Budget Per Phase

Each phase has a target token budget for incoming/outgoing context:

Phase	Purpose	Incoming Budget	Outgoing Budget	Notes
Phase 0	Planning	~500 tokens	~800 tokens	User intent → plan outline
Phase 1	Requirements	~300 tokens	~1500 tokens	Context → detailed requirements
Phase 2	Research	~800 tokens	~2000 tokens	Requirements → patterns + references
Phase 3	Architecture	~1000 tokens	~1500 tokens	Research → design decisions
Phase 4	Build	~2000 tokens	~3000 tokens	Design → complete file
Phase 5-6	Agents	~1500 tokens	~2500 tokens	Dependencies → agent files
Phase 7	Validation	~2500 tokens	~1000 tokens	File → validation report
Phase 8	Integration	~500 tokens	~300 tokens	Status → completion report

Information Compression Patterns

Reference-First Pattern

Instead of passing full file contents, pass references with key excerpts:

# ❌ Token-Heavy (passes full content)
context: |
  Here is the existing file content:
  [2000 lines of file content...]
  
  Analyze and improve this.

# ✅ Token-Efficient (passes reference + key sections)
context: |
  File: `.github/prompts/validator.prompt.md`
  
  Key Sections to Improve:
  - Goal (lines 15-20): "Validate prompts..."
  - Tools (lines 45-60): Uses 5 tools currently
  - Constraints (lines 80-95): Missing boundary definitions
  
  Use read_file to access full content if needed.
  Focus improvements on identified sections.

Progressive Summarization Pattern

Each phase summarizes for the next, not for all future phases:

# Phase 2 → Phase 3 Handoff
context: |
  ## Requirements Summary (from Phase 1)
  Goal: Validate prompt files for structure compliance
  Role: Technical Validator
  Scope: IN=markdown files, OUT=code generation
  
  ## Research Findings (from Phase 2)
  Patterns Discovered:
  1. YAML frontmatter validation (see pattern-a.md)
  2. Section structure checks (see pattern-b.md)
  3. Tool count verification (3-7 range)
  
  ## YOUR TASK (Phase 3)
  Design architecture for implementing above patterns.

Selective Context Rules

Information Type	Pass Forward?	Reason
User’s original request	✅ Always	Maintains intent alignment
Goal statement	✅ Always	Core reference for all phases
Role description	✅ Always	Constrains behavior
Use case challenge results	⚠️ Summary only	Full results too verbose
Research file paths	✅ References	Agent can read if needed
Research file contents	❌ Never	Too token-heavy
Architecture decisions	✅ Key decisions	Guides implementation
Build output (file)	✅ Full content	Needed for validation
Validation errors	✅ Full details	Needed for fixes

Handoff Reliability Patterns

Checksum Pattern for Critical Data

For data that must survive handoff intact:

context: |
  ## Goal (CRITICAL - verify preserved)
  Text: "Analyze and validate prompt files for structural compliance"
  Checksum: goal-hash-7f3a2b
  
  ## Tools (CRITICAL - verify count)
  Count: 5
  List: [read_file, grep_search, list_dir, semantic_search, file_search]
  Checksum: tools-hash-9c4e1d
  
  At end of your phase, confirm:
  - Goal text unchanged ✅/❌
  - Tool count unchanged ✅/❌
  - If changed, document reason

Explicit Acknowledgment Pattern

Require agents to acknowledge critical handoff data:

# Orchestrator instruction to receiving agent
context: |
  Before proceeding, confirm you received:
  1. Goal statement: [quote it back]
  2. Role definition: [quote it back]
  3. Scope boundaries: [list IN/OUT items]
  
  If any are unclear or missing, request clarification
  before beginning your task.

Phase Transition Templates

Standard Handoff Template

## Handoff: Phase {N} → Phase {N+1}

### Summary from Phase {N}
{2-3 sentence summary of what was accomplished}

### Key Outputs
- Output 1: {brief description} [reference: path/file.md]
- Output 2: {brief description} [reference: inline below]

### Critical Data (verify preserved)
- Goal: "{goal statement}"
- Role: "{role statement}"
- Scope: IN=[list], OUT=[list]

### Phase {N+1} Task
{Specific instructions for next phase}

### Success Criteria
1. {Measurable criterion 1}
2. {Measurable criterion 2}
3. {Measurable criterion 3}

Error State Handoff Template

When a phase encounters issues:

## Handoff: Phase {N} → Error Recovery

### Error Encountered
Type: {ambiguity/conflict/missing-info/tool-failure}
Description: {What went wrong}

### Context at Error Point
- Completed Steps: {list}
- Failed Step: {step name}
- Remaining Steps: {list}

### Recovery Options
1. {Option A}: {description + impact}
2. {Option B}: {description + impact}
3. Return to Phase {M}: {if backtrack needed}

### User Decision Required
{Specific question for user to resolve}

Anti-Patterns to Avoid

Anti-Pattern	Problem	Solution
Context Dumping	Passing all prior context to each phase	Use progressive summarization
Reference Omission	Not providing file paths for context	Always include actionable references
Implicit Expectations	Assuming agent knows what to return	Explicitly state required outputs
Unbounded Output	No guidance on output length	Specify token/line budgets
Silent Failures	Agent proceeds despite missing data	Require acknowledgment of critical data

Implementation Roadmap

Stage 1: Agent Infrastructure (Week 1, Days 1-3)

Priority: CRITICAL - Agents are dependencies for orchestrators

Day	Task	Output
1	Create `agent-researcher.agent.md`	Agent file with role challenge capabilities
1	Create `agent-validator.agent.md`	Agent file with tool alignment checks
2	Create `agent-builder.agent.md`	Agent file with tool count verification
2	Create `agent-updater.agent.md`	Agent file with alignment preservation
3	Test all 4 agents independently	Test results documented
3	v1.107 Testing: Test agents in background context with work trees	Verify isolation works

Stage 2: Update Existing Prompt Agents (Week 1, Days 3-4)

Priority: HIGH - Enhance existing agents with v2 capabilities

Day	Task	Output
3	Update `prompt-researcher.agent.md`	Added use case challenge methodology
3	Update `prompt-validator.agent.md`	Added tool alignment validation
4	Update `prompt-builder.agent.md`	Added pre-save validation
4	Update `prompt-updater.agent.md`	Added change categorization
4	v1.107 Testing: Test “Continue in” delegation from chat	Verify context transfer

Stage 3: Create Orchestration Prompts (Week 1-2, Days 5-8)

Priority: MEDIUM - Build on agent infrastructure

Day	Task	Output
5	Create `agent-design-and-create.prompt.md`	Full orchestrator with Phase 0-8 (planning mode)
6	Create `agent-review-and-validate.prompt.md`	Validation orchestrator
7	Update `prompt-design-and-create.prompt.md`	Enhanced with Phase 0, 5-6
8	Update `prompt-review-and-validate.prompt.md`	Minor enhancements
8	v1.107 Testing: Test Agent HQ session management	Verify all phases tracked

Stage 4: Integration Testing (Week 2, Days 9-10)

Day	Task	Output
9	End-to-end test: Create test prompt	Working prompt file
9	End-to-end test: Create test agent	Working agent file
9	v1.107 Testing: Test planning mode (Phase 0)	Verify plan generation works
10	End-to-end test: Validation workflows	Both review-validate prompts working
10	End-to-end test: Agent dependencies	Phase 5-6 agent plans work
10	v1.107 Testing: Test background validation with work trees	Verify parallel execution

Stage 5: Documentation and Migration (Week 2, Days 11-12)

Day	Task	Output
11	Add deprecation notices to v2 files	Notices pointing to new workflows
11	Update this planning document	Mark stages complete
11	v1.107 Documentation: Document Agent HQ workflow patterns	Usage guide for session management
12	Team training documentation	Usage guide for new workflows + v1.107 features
12	Update tech/ articles	References to new system and v1.107 capabilities

Success Criteria

Reliability Metrics

Metric	Target	Measurement
Agent tool count	100% agents have 3-7 tools	YAML validation
Tool alignment	100% agents pass alignment check	Validator reports
Validation pass rate	90%+ first-time pass	Track Phase 7 results
Issue resolution cycles	≤2 loops to resolution	Track Phase 7↔︎8 iterations

Quality Metrics

Metric	Target	Measurement
Use case coverage	100% of roles challenged	Phase 1 completion
Boundary completeness	100% have three-tier	Validator check
Template compliance	100% follow patterns	Pattern consistency score

Workflow Metrics

Metric	Target	Measurement
Time to create prompt	<15 minutes	Time tracking
Time to create agent	<20 minutes	Time tracking
User approval rate	>90% plans approved as-is	Phase transition tracking

File Checklist Summary

Orchestration Prompts

File	Status	Action
`prompt-design-and-create.prompt.md`	🔄	UPDATE (add Phase 5-6)
`prompt-review-and-validate.prompt.md`	🔄	UPDATE (minor)
`agent-design-and-create.prompt.md`	⬜	CREATE NEW
`agent-review-and-validate.prompt.md`	⬜	CREATE NEW

Agent Files - Existing (Prompt)

File	Status	Action
`prompt-researcher.agent.md`	🔄	UPDATE (add use case challenge)
`prompt-builder.agent.md`	🔄	UPDATE (add pre-save validation)
`prompt-updater.agent.md`	🔄	UPDATE (add change categorization)
`prompt-validator.agent.md`	🔄	UPDATE (add tool alignment)

Agent Files - New (Agent)

File	Status	Action
`agent-researcher.agent.md`	⬜	CREATE NEW
`agent-builder.agent.md`	⬜	CREATE NEW
`agent-updater.agent.md`	⬜	CREATE NEW
`agent-validator.agent.md`	⬜	CREATE NEW

Instruction Files

File	Status	Action
`prompts.instructions.md`	✅	NO CHANGES
`agents.instructions.md`	✅	NO CHANGES

Files to Deprecate (After Validation)

File	Status	Migration Path
`agent-createorupdate-agent-file-v2.prompt.md`	📦	→ `agent-design-and-create.prompt.md`
`prompt-createorupdate-prompt-file-v2.prompt.md`	📦	→ `prompt-design-and-create.prompt.md`

Next Steps

Immediate Actions

✅ Review this plan - Approve architecture and approach
⬜ Create agent-researcher.agent.md - First new agent
⬜ Create agent-validator.agent.md - Second new agent
⬜ Create agent-builder.agent.md - Third new agent
⬜ Create agent-updater.agent.md - Fourth new agent

Upon Plan Approval

Execute Stage 1-5 following the implementation roadmap above.

Document Version: 2.0
Created: 2025-12-14
Last Updated: 2025-12-14
Status: Ready for Review
Author: GitHub Copilot (Claude Opus 4.5)

Multi-Agent Orchestration Plan V2 for Prompt and Agent File Creation

Executive Summary

v1.107 Enhancements

Files to Create/Update Summary

Table of Contents

Analysis of Source Prompts

Source 1: prompt-createorupdate-prompt-file-v2.prompt.md

Source 2: agent-createorupdate-agent-file-v2.prompt.md

Architecture Overview

Design Principles

Architecture Diagram

Orchestration Prompts Specifications

1. prompt-design-and-create.prompt.md

YAML Frontmatter

Role Definition

Phase Workflow

Phase 1 Implementation Details: Use Case Challenge Protocol

Step 1: Extract Initial Requirements

Step 2: Determine Complexity Level

Step 3: Use Case Challenge Execution

Step 4: Expected Output Format

Step 5: Orchestrator Presents to User

Step 6: Approval and Routing

Integration: When Use Cases Reveal Agent Needs

Boundaries

2. prompt-review-and-validate.prompt.md

YAML Frontmatter

Phase Workflow

3. agent-design-and-create.prompt.md

YAML Frontmatter

Phase Workflow

4. agent-review-and-validate.prompt.md

YAML Frontmatter

Phase Workflow

Agent Specifications

Existing Agents to UPDATE (4 files)

1. prompt-researcher.agent.md

3. prompt-updater.agent.md

Role Definition

Key Processes

Phase 2: Pattern Discovery

Phase 3: Structure Definition

6. agent-builder.agent.md

Full Specification

Role Definition

Boundaries

7. agent-updater.agent.md

Full Specification

Key Processes

Boundaries

8. agent-validator.agent.md

Full Specification

Key Validation Checks

Output Format

Instruction Files Assessment

.github/instructions/prompts.instructions.md

.github/instructions/agents.instructions.md

Handoff Flow Diagrams

Prompt Design and Create Flow

Agent Design and Create Flow

Communication Protocols & Information Contracts

Phase-to-Phase Data Flow

Information Compression Between Phases

Compressed Handoff to Phase 3 (500 tokens):

Example: Phase 4 → Phase 5 Handoff (Build → Validation)

Selective Context Passing Rules

Reliability Checksum Pattern

📊 Data Exchange Optimization

Token Budget Per Phase

Information Compression Patterns

Reference-First Pattern

Progressive Summarization Pattern

Selective Context Rules

Handoff Reliability Patterns

Checksum Pattern for Critical Data

Explicit Acknowledgment Pattern

Phase Transition Templates

Standard Handoff Template

Error State Handoff Template

Anti-Patterns to Avoid

Source 1: `prompt-createorupdate-prompt-file-v2.prompt.md`

Source 2: `agent-createorupdate-agent-file-v2.prompt.md`

1. `prompt-design-and-create.prompt.md`

2. `prompt-review-and-validate.prompt.md`

3. `agent-design-and-create.prompt.md`

4. `agent-review-and-validate.prompt.md`

1. `prompt-researcher.agent.md`

3. `prompt-updater.agent.md`

6. `agent-builder.agent.md`

7. `agent-updater.agent.md`

8. `agent-validator.agent.md`

`.github/instructions/prompts.instructions.md`

`.github/instructions/agents.instructions.md`